home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 001 / prcm_cmd.arc / CMDFILES.DOC
Text File  |  1987-01-18  |  22KB  |  583 lines
  1.  
  2.  
  3.                         7.  C O M M A N D   F I L E S 
  4.              
  5.  
  6.  
  7.  
  8.     Command files are text files you create that contain ProComm commands. 
  9.     You can use command files to perform automatic logons, perform unattended
  10.     file transfers and many other tasks.  You can even link command files to
  11.     the entries in your dialing directory so that the entire dialing and
  12.     logon procedure is automated.
  13.  
  14.     You can create a command file using virtually any word processor which
  15.     saves in straight ASCII format; if your word processor normally makes use
  16.     of special or extended ASCII characters, then you should use its
  17.     "non-document" mode.   A command file may have any valid filename;
  18.     however, ProComm looks for files with an extension of .CMD when it lists
  19.     available command files.  
  20.  
  21.     Command files can be executed from within ProComm or as a command line
  22.     option when you first invoke the program.  If you specify them on the
  23.     command line, using the "/F" option, they will be executed immediately
  24.     upon program startup.  Execute them from inside the program by pressing
  25.     Alt-F5.  ProComm first searches the current directory for files with the
  26.     .CMD extension.  If any are found, their names are displayed in the
  27.     window.  If none are found, ProComm will look in the directory pointed to
  28.     by the ProComm environment variable.  Again, the names of any files found
  29.     are displayed in the window.  If no files are found in either directory,
  30.     the  message "NO FILES" will be displayed.  
  31.  
  32.     To execute a command file you may either type the filename or choose from
  33.     the scrolling window display of available .CMD files.  If you type the
  34.     filename, you may omit the .CMD extension.  To choose from the scrolling
  35.     window, position the highlight on the name of the file you wish to
  36.     execute and press <CR>.  PgUp and PgDn will scroll the window one page in
  37.     either direction.  The arrow keys will scroll the window one entry in
  38.     either direction.  Pressing the Home key will position the list at the
  39.     first page of available command files; pressing End will position it at
  40.     the last.  If you don't see the highlighted entry, use the Alt-Z command
  41.     to change the color being used for highlighting so that it is different
  42.     than that being used for regular foreground display.  The command file
  43.     window uses the colors displayed in Alt-Z for the file transfer window.
  44.  
  45.     Once you begin to enter a command file name at the prompt you may still
  46.     scroll the window, but you may not select a file for execution from the
  47.     scrolling display.  
  48.  
  49.     Abort a command file by pressing <ESC> during its execution.  The command
  50.     file will abort when the current command has completed (which might take
  51.     a few seconds).  In some cases, such as while dialing or performing a
  52.     file transfer, two <ESC>'s are needed: one to abort the task in progress
  53.     and a second to abort the command file.
  54.  
  55.     There is a special command file named PROFILE.CMD which ProComm looks for
  56.     in the default directory first, then in the directory pointed to by the
  57.  
  58.  
  59.     Copyright (C) 1986 Datastorm Technologies, Inc.                      701
  60.  
  61.  
  62.  
  63.    ProComm 2.4                                                 Command Files
  64.  
  65.  
  66.     ProComm environment variable (see Section 1).  If PROFILE.CMD is found,
  67.     it will be executed immediately upon program startup, before any other
  68.     command file specified as a "/F" command line option.  You can use the
  69.     profile to do such custom setup work as changing to a special directory,
  70.     turning off the sound, changing line settings, or overriding the default
  71.     modem initialization string.
  72.  
  73.  
  74.     Command File Syntax
  75.  
  76.     Command file commands begin with special command words, listed below.
  77.     Commands may be entered in either upper- or lower-case.  When processing
  78.     commands ProComm looks only at the first 4 characters.  Thus all the
  79.     following commands are treated the same:  
  80.  
  81.           TRANSMIT = trans = Tran = TRANSM
  82.  
  83.     Each command must appear on a separate line.
  84.  
  85.          IF NOT CONNECTED                   ; this is correct
  86.             MESSAGE "sorry!"                ;
  87.          ENDIF                              ;
  88.  
  89.          IF NOT CONNECTED MESSAGE "sorry!"  ; this is incorrect
  90.          ENDIF                              ;
  91.  
  92.     Many commands have one or more additional arguments; if the argument is
  93.     listed in brackets ([]) it is optional, otherwise it is required. 
  94.     Arguments listed within quotation marks (" ") should include the
  95.     quotation marks; thus the command RUN, if you wish to use it to run
  96.     WordStar, would be typed
  97.  
  98.           RUN "WORDSTAR"
  99.  
  100.     Arguments may be separated by blanks or commas.  Thus both
  101.  
  102.           GETFILE XMODEM "FILE.EXT"
  103.  
  104.     and 
  105.  
  106.           GETFILE,XMODEM,"FILE.EXT"
  107.  
  108.     are valid.
  109.  
  110.     To use the quotation character in a quoted string, precede it with the
  111.     special escape character ` (the reverse tick mark, or accent grave, ASCII
  112.                             `
  113.     96).  Thus to print the message
  114.  
  115.           She said "Goodbye" and then went home.
  116.  
  117.     use the command
  118.  
  119.           MESSAGE "She said `"Goodbye`" and then went home."
  120.  
  121.     Labels are used as targets of GOTOs and GOSUBs.  Labels must end with a
  122.     colon.  Below are some valid labels:
  123.  
  124.             LABEL1:
  125.  
  126.  
  127.     Copyright (C) 1986 Datastorm Technologies, Inc.                      702
  128.  
  129.  
  130.  
  131.    ProComm 2.4                                                 Command Files
  132.  
  133.  
  134.             This_is_a_long_label:
  135.             JUMP1:
  136.             split:
  137.             GO_HERE:
  138.  
  139.     Labels must appear on a line by themselves.  (Comments are allowed on
  140.     label lines; executable statements are not).  Labels may be of any
  141.     length; however, only the first 8 characters are used by the interpreter. 
  142.     Thus LABEL_TAG1: and LABEL_TAG2 are the same as far as ProComm is
  143.     concerned.
  144.  
  145.     Comments begin with a semi-colon (;).  Any text following a semi-colon is
  146.     treated as comment text.  Below are valid comments:
  147.  
  148.             ; This is a comment.
  149.             LABEL7:                   ;This is a comment on a label line
  150.             TRANSMIT "Welcome back"   ;And this is a comment as well
  151.  
  152.     There are 10 string variables, named S0-S9, which may be set and used in
  153.     place of quoted strings.  They have a maximum length of 80 characters
  154.     each.  They may be set by the ASSIGN, GET and RGET commands.  String
  155.     variables may be used in place of a quoted string in any of the commands
  156.     marked below with the @ character.  For example, the commands
  157.  
  158.           ASSIGN S5 "Hello, Mike Todd here"
  159.  
  160.              
  161.          TRANSMIT S5
  162.  
  163.     and
  164.  
  165.           TRANSMIT "Hello, Mike Todd here"
  166.  
  167.     are functionally the same.  One of the most useful applications of string
  168.     variables is in obtaining and using user responses.  Consider the
  169.     commands below:
  170.  
  171.           MESSAGE "Enter the name of the file to upload:"
  172.  
  173.              
  174.          GET S4
  175.  
  176.              
  177.          SENDFILE XMODEM S4
  178.  
  179.     String variables are also a very handy method for passing values between
  180.     command files.  When you chain from command file to command file, using
  181.     the EXECUTE command, string variable contents are not reset.  Thus you
  182.     may set a variable in one command file, and act on the variable in
  183.     another.
  184.  
  185.     ProComm allows the nesting of commands such as IF, SWITCH and GOSUB. 
  186.     Nesting, however, is limited to 10 levels.
  187.  
  188.     Characters that are received from a remote system are stored in the
  189.     receive buffer.  During command file execution, the receive buffer is
  190.     emptied before each command is executed, with the exceptions noted below.
  191.     What this means is that before each command is performed, all the
  192.     characters that have come in are displayed on the screen and are
  193.     therefore not available to be processed by later commands.  The
  194.     exceptions are the GET, RGET and WAITFOR commands, as well as labels and
  195.     comments.  In these cases the buffer is not emptied, allowing the command
  196.     to process the accumulated characters.  The point here is that if you
  197.     have a command sequence that looks like
  198.  
  199.  
  200.     Copyright (C) 1986 Datastorm Technologies, Inc.                      703
  201.  
  202.  
  203.  
  204.    ProComm 2.4                                                 Command Files
  205.  
  206.  
  207.  
  208.           TRANSMIT "password!"
  209.  
  210.              
  211.          PAUSE 5
  212.  
  213.              
  214.          SET DUPLEX HALF
  215.  
  216.              
  217.          WAITFOR "target"
  218.  
  219.     the text you are looking for may come in and be processed before the
  220.     WAITFOR command has a chance to see it.  A better solution would be to
  221.     change duplex at some other point, and let the WAITFOR command do the
  222.     extra pausing:
  223.  
  224.           SET DUPLEX HALF
  225.           TRANSMIT "password!"
  226.           WAITFOR "target" 35           ; 30 seconds is the default pause
  227.  
  228.  
  229.     Use the commands described below to perform your specific task.  Be sure
  230.     to test your command files thoroughly before using them for unattended
  231.     communications.  
  232.  
  233.     The following notations apply to the commands listed below:  Commands
  234.     marked with an asterisk (*) may be tested with the IF command.  Commands
  235.     marked with an at-sign (@) indicate where string variables may be used in
  236.     place of quoted strings.  Sx indicates that you should use one of the
  237.     string variables.  Ellipses (...) mean that you may place a number of
  238.     command lines in that spot.
  239.  
  240.  
  241.                                Top Level Commands
  242.              
  243.  
  244.  
  245.     ALARM [seconds] 
  246.  
  247.     The ALARM command will sound an alarm to alert you to some event.  Use
  248.     the [seconds] option to determine the amount of time the alarm will
  249.     sound.  If the [seconds] option is not specified ProComm will use the
  250.     Alarm Time specified in the General SetUp screen.  This command is also
  251.     under control of the Alarm Sound setting.  Both Alarm Sound and Alarm
  252.     Time may be regulated using the SET command described below.
  253.  
  254.     Example:   ALARM 5             ; sounds the alarm for 5 seconds
  255.  
  256.  
  257.     ASSIGN Sx "string"        @
  258.  
  259.     This command assigns the contents of "string" to a user variable.  Use
  260.     ASSIGN to set a user variable from within your command file.
  261.  
  262.     Examples:  ASSIGN S5 "12345"   ; set S5 to contain the string '12345'
  263.                ASSIGN S6 S5        ; sets S6 to be the same as S5
  264.  
  265.  
  266.     BREAK [time]
  267.  
  268.     The BREAK command is used to send a break to the remote system.  The
  269.     optional [time] argument determines the length of the break in
  270.     milliseconds.  If [time] is not specified, ProComm will use the default
  271.     as indicated by the Break Length option in the Terminal SetUp screen.
  272.  
  273.  
  274.     Copyright (C) 1986 Datastorm Technologies, Inc.                      704
  275.  
  276.  
  277.  
  278.    ProComm 2.4                                                 Command Files
  279.  
  280.  
  281.  
  282.     Examples:  BREAK               ; send a break using the default timing
  283.  
  284.                BREAK 500           ; send a 500 millisecond break
  285.  
  286.  
  287.     CHDIR "drive and/or directory"        @
  288.  
  289.     The CHDIR command will change the logged directory and/or drive.
  290.  
  291.     Examples:  CHDIR "A:"          ; change the logged drive to A:
  292.  
  293.                CHDIR "C:\COMM"     ; change to \COMM dir on drive C:
  294.  
  295.                CHDIR "\COMM"       ; change logged dir to \COMM
  296.  
  297.  
  298.     CLEAR [bg fg]
  299.  
  300.     The CLEAR command is used to clear the top 24 lines of your screen.  The
  301.     optional parameter [bg fg] (you must use both codes) allows you to change
  302.     your background (bg) and foreground (fg) colors.  If the [bg fg] option
  303.     is not used, the screen will be cleared to the current colors.  If the
  304.     [bg fg] option is used, ProComm will clear the screen to the new colors
  305.     as well as reset the current colors to those specified.  The codes to use
  306.     for colors are as follows:
  307.  
  308.           0 Black                   8 Dk Grey        (8-15 are the bright
  309.           1 Blue                    9 Lt Blue         colors)
  310.           2 Green                  10 Lt Green
  311.           3 Cyan                   11 Lt Cyan
  312.           4 Red                    12 Lt Red
  313.           5 Magenta                13 Lt Magenta
  314.           6 Brown                  14 Yellow
  315.           7 Lt Grey                15 White
  316.  
  317.     Only the codes 0-7 are valid for background colors; any of the sixteen
  318.     colors may be used for the foreground.
  319.  
  320.     Examples:  CLEAR 0 10          ; clear screen to lt green on black
  321.  
  322.                CLEAR               ; clear screen to current colors
  323.  
  324.  
  325.     DIAL "entry"        @
  326.  
  327.     The DIAL command is used to call an entry in your dialing directory. 
  328.     Specify the number of the entry, optionally preceded and/or followed by a
  329.     long distance code identifier as the argument.
  330.  
  331.     Examples:  DIAL "5"            ; call entry number 5
  332.  
  333.                DIAL "#5"           ; call entry 5 using ld code '#'
  334.  
  335.     If a second command file is linked via the dialing directory to the entry
  336.     being dialed, the linked command file will not be executed.  Place all
  337.     statements to be executed in the command file which initiates the call.  
  338.  
  339.  
  340.  
  341.     Copyright (C) 1986 Datastorm Technologies, Inc.                      705
  342.  
  343.  
  344.  
  345.    ProComm 2.4                                                 Command Files
  346.  
  347.  
  348.     Use the IF LINKED command to avoid secondary dialing in command files
  349.     linked to dialing directory entries.  For example, including the commands
  350.  
  351.           IF NOT LINKED            ; do not execute the dial command if
  352.                DIAL "5"            ; this file is executing via linkage
  353.           ENDIF                    ; to a dialing directory entry
  354.  
  355.     in a command file linked to entry number 5 allows you to use that command
  356.     file both as a stand alone file and linked to the dialing directory
  357.     entry.
  358.  
  359.     This command uses the auto redial facility to place its calls; it will
  360.     keep re-dialing until a connection is made.  To make a call without using
  361.     auto redial, use the TRANSMIT command.
  362.  
  363.     Examples:  TRANSMIT "ATDT1 314 449-9401!"     ; place the call
  364.                PAUSE 10                           ; wait 10 seconds
  365.                IF CONNECTED
  366.                     ...                           ; do these commands if
  367.                ENDIF                              ; connected
  368.  
  369.     Remember, if you sort your dialing directory you will need to change your
  370.     command files so the entry numbers match.
  371.  
  372.  
  373.     DOS "command" [WAIT]        @ *
  374.  
  375.     The DOS command allows you to execute DOS commands or other programs from
  376.     within a ProComm .CMD file.  Enter the "command" as it would appear on
  377.     the DOS command line.  For example, to go out to DOS and type a file
  378.     named FILE.EXT to your printer use the command:
  379.  
  380.           DOS "type FILE.EXT > prn"
  381.  
  382.     If the optional argument WAIT is included, ProComm will wait for a
  383.     keystroke after executing the command, before returning to ProComm.
  384.  
  385.     To execute this command properly you must make sure of two things. 
  386.     First, you must have enough memory to run the "command".  Secondly,
  387.     COMMAND.COM must be where ProComm can find it.  (Either in the boot
  388.     location or wherever COMSPEC is pointing).  While this command returns an
  389.     error status checkable with the IF command, the error check is very
  390.     limited.  The DOS command will indicate FAILURE only if COMMAND.COM was
  391.     not found.  IF COMMAND.COM was found, even if the command to be executed
  392.     was invalid, SUCCESS will be returned.
  393.  
  394.     Examples:  DOS "del FILE.EXT"       ; delete a file
  395.  
  396.                DOS "sortdisk"           ; run a program called sortdisk
  397.                IF FAILURE
  398.  
  399.                    MESSAGE "COMMAND.COM not found"
  400.  
  401.               ENDIF
  402.  
  403.     CAUTION: If you execute a program or command requiring user input be sure
  404.     you are around to provide it, since the program will wait until you do.
  405.  
  406.  
  407.     EMULATE terminal -or- EMULATE "terminal"
  408.  
  409.  
  410.     Copyright (C) 1986 Datastorm Technologies, Inc.                      706
  411.  
  412.  
  413.  
  414.    ProComm 2.4                                                 Command Files
  415.  
  416.  
  417.  
  418.     The EMULATE command changes the active emulation to that specified. 
  419.     Valid terminal types are: VT100, VT52, IBM3101, TV920, TV950, ADM5,
  420.     HEATH19, ANSI, ADDSVP and WYSE100.
  421.  
  422.     Examples:  EMULATE VT100       ; change emulation to VT100
  423.  
  424.                EMULATE "IBM3101"   ; emulate the 3101
  425.  
  426.  
  427.     EXECUTE "cmd file"        @
  428.  
  429.     The EXECUTE command allows you to begin execution of a different command
  430.     file.  The currently executing command file will be ended and will not be
  431.     returned to.   The EXECUTE commands allows a one-way chaining of command
  432.     file execution.  The file extension of .CMD need not be specified.
  433.  
  434.     Remember, string variables are not reset when chaining command files so
  435.     you may use them to pass values.  String variables are reset to null,
  436.     however, when you begin the first command in the chain.
  437.  
  438.     Examples:  EXECUTE "CALL_KEN.CMD"        ; execute CALL_KEN.CMD
  439.  
  440.                SWITCH S0                     ; switch based on option
  441.                     CASE "A"
  442.  
  443.                         ASSIGN S1 "CHOICEA.CMD"
  444.  
  445.                    ENDCASE
  446.  
  447.                    CASE "B"
  448.  
  449.                         ASSIGN S1 "CHOICEB.CMD"
  450.  
  451.                    ENDCASE
  452.  
  453.                    DEFAULT
  454.  
  455.                         ASSIGN S1 "DEFAULT.CMD"
  456.  
  457.                    ENDCASE
  458.  
  459.               ENDSWITCH
  460.  
  461.               EXECUTE S1
  462.  
  463.  
  464.     EXIT
  465.  
  466.     The EXIT command terminates the executing command file and returns you to
  467.     Terminal Mode.
  468.  
  469.     Examples:  TRANSMIT "Goodbye"       ; log off remote
  470.                HANGUP                   ; hangup phone
  471.                EXIT                     ; return to Terminal Mode
  472.  
  473.  
  474.     FIND Sx "target"        @ *
  475.  
  476.     The FIND command looks for an occurrence of the "target" string in the
  477.     string variable Sx.  Test for an occurrence of "target" within Sx using
  478.     the IF FOUND command.  The FIND command is not case sensitive.
  479.  
  480.     Examples:  MESSAGE "Enter the password:"      ; prompt
  481.                MGET S0                            ; get with mask
  482.                FIND S0 "password"                 ; look for password
  483.                IF NOT FOUND                       ; found ?
  484.  
  485.  
  486.     Copyright (C) 1986 Datastorm Technologies, Inc.                      707
  487.  
  488.  
  489.  
  490.    ProComm 2.4                                                 Command Files
  491.  
  492.  
  493.                     MESSAGE "Invalid password"    ; not found, do this code
  494.                     GOTO SECURITY_BREACH
  495.  
  496.               ELSE
  497.  
  498.                    GOSUB WELCOME                 ; found, do this
  499.                ENDIF
  500.  
  501.  
  502.     GET Sx [length]
  503.  
  504.     The GET command is used to obtain and store user input.  The Sx argument
  505.     determines which string variable is used to hold the data.  The optional
  506.     [length] variable determines the maximum number of characters that will
  507.     be accepted.  If the [length] argument is not specified, the maximum size
  508.     of 80 characters is used.
  509.  
  510.     When responding to a GET command, the user must enter a <CR> to signal
  511.     that his input is complete.  The <CR> is not included in the string
  512.     variable.  If the [length] argument is used, the user will be allowed to
  513.     enter up to [length] number of characters, but still must use a <CR> to
  514.     complete his entry.  ProComm will beep if the user attempts to enter more
  515.     than [length] characters.
  516.  
  517.     The MGET command is the same as the GET command except that the text the
  518.     user enters is not displayed; rather each character typed will display as
  519.     an asterisk (*).  This is handy for security-related items such as
  520.     passwords.
  521.  
  522.     Examples:  MESSAGE "Enter your choice: (A,B or C)"
  523.  
  524.               GET S3 1
  525.  
  526.               SWITCH S3
  527.  
  528.                    ...
  529.  
  530.               ENDSWITCH
  531.  
  532.                MESSAGE "Enter the password"
  533.  
  534.               MGET S9 8
  535.  
  536.               FIND S9 "secret"
  537.  
  538.               IF NOT FOUND
  539.  
  540.                    MESSAGE "You are not an authorized user."
  541.  
  542.                    QUIT
  543.  
  544.               ENDIF
  545.  
  546.  
  547.     GETFILE
  548.             KERMIT                     *
  549.             XMODEM "filename"        @ *
  550.             WXMODEM "filename"       @ *     (Widowed XMODEM)
  551.             RXMODEM "filename"       @       (Relaxed XMODEM)
  552.             YMODEM "filename"        @ *
  553.             BYMODEM                    *     (YMODEM Batch)
  554.             TELINK                     *
  555.             MODEM7                     *
  556.             ASCII "filename"         @ *
  557.             CISB                       *     (CompuServe B)
  558.  
  559.     The GETFILE command performs a file download (receive).  A number of
  560.     protocols are currently supported; see the section on file transfers for
  561.     more information on each protocol.  
  562.  
  563.  
  564.  
  565.     Copyright (C) 1986 Datastorm Technologies, Inc.                      708
  566.  
  567.  
  568.  
  569.    ProComm 2.4                                                 Command Files
  570.  
  571.  
  572.     To perform a download you must first initiate the transfer on the remote. 
  573.     When that system indicates that it is ready, begin your transfer.
  574.  
  575.     Note that 4 protocols require you to specify the filename to receive; for
  576.     the other protocols, the filename is provided by the sending system.  All
  577.     transfers may be checked for successful completion using the IF
  578.     SUCCESS/FAILURE command.
  579.  
  580.     Examples:  WAITFOR "Begin your transfer now"  ; wait till it's ready
  581.                GETFILE XMODEM "FILE.EXT"          ; receive FILE.EXT
  582.  
  583.